﻿using DKPScoreWebApi.DTOs.Requests;
using DKPScoreWebApi.DTOs.Results;
using DKPScoreWebApi.Models;

namespace DKPScoreWebApi.Services.Interfaces
{
    /// <summary>
    /// DKP积分管理服务接口
    /// 定义积分相关的业务逻辑操作
    /// </summary>
    public interface IDkpService
    {
        /// <summary>
        /// 为成员添加积分
        /// </summary>
        /// <param name="userId">操作用户ID</param>
        /// <param name="guildId">工会ID</param>
        /// <param name="request">添加积分请求数据</param>
        /// <returns>积分操作结果</returns>
        Task<PointResult> AddPointsAsync(int userId, int guildId, AddPointsRequest request);

        /// <summary>
        /// 更新成员进度
        /// </summary>
        /// <param name="userId">操作用户ID</param>
        /// <param name="guildId">工会ID</param>
        /// <param name="request">更新进度请求数据</param>
        /// <returns>进度操作结果</returns>
        Task<ProgressResult> UpdateProgressAsync(int userId, int guildId, UpdateProgressRequest request);

        /// <summary>
        /// 获取成员的积分记录
        /// </summary>
        /// <param name="guildId">工会ID</param>
        /// <param name="memberId">成员ID</param>
        /// <param name="startDate">开始日期，可选</param>
        /// <param name="endDate">结束日期，可选</param>
        /// <returns>积分记录列表</returns>
        Task<List<PointRecord>> GetMemberRecordsAsync(int guildId, int memberId, DateTime? startDate = null, DateTime? endDate = null);

        /// <summary>
        /// 获取工会积分排行榜
        /// </summary>
        /// <param name="guildId">工会ID</param>
        /// <param name="topCount">返回前N名，默认为50</param>
        /// <returns>成员排名列表</returns>
        Task<List<GuildMember>> GetGuildRankingAsync(int guildId, int topCount = 50);

        /// <summary>
        /// 获取工会的积分项目列表
        /// </summary>
        /// <param name="guildId">工会ID</param>
        /// <returns>积分项目列表</returns>
        Task<List<PointItem>> GetGuildPointItemsAsync(int guildId);

        /// <summary>
        /// 创建积分项目
        /// </summary>
        /// <param name="guildId">工会ID</param>
        /// <param name="request">创建项目请求数据</param>
        /// <returns>创建的积分项目实体</returns>
        Task<PointItem> CreatePointItemAsync(int guildId, CreateItemRequest request);

        /// <summary>
        /// 更新积分项目
        /// </summary>
        /// <param name="itemId">项目ID</param>
        /// <param name="request">更新请求数据</param>
        /// <returns>true表示更新成功，false表示失败</returns>
        Task<bool> UpdatePointItemAsync(int itemId, CreateItemRequest request);

        /// <summary>
        /// 删除积分项目（软删除）
        /// </summary>
        /// <param name="itemId">项目ID</param>
        /// <returns>true表示删除成功，false表示失败</returns>
        Task<bool> DeletePointItemAsync(int itemId);

        /// <summary>
        /// 根据ID获取积分项目详情
        /// </summary>
        /// <param name="itemId">项目ID</param>
        /// <returns>积分项目实体</returns>
        Task<PointItem> GetPointItemByIdAsync(int itemId);

        /// <summary>
        /// 获取工会的积分记录
        /// </summary>
        /// <param name="guildId">工会ID</param>
        /// <param name="startDate">开始日期，可选</param>
        /// <param name="endDate">结束日期，可选</param>
        /// <param name="memberId">成员ID，可选</param>
        /// <returns>积分记录列表</returns>
        Task<List<PointRecord>> GetGuildRecordsAsync(int guildId, DateTime? startDate = null, DateTime? endDate = null, int? memberId = null);
    }
}
